home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 June / EnigmA AMIGA RUN 08 (1996)(G.R. Edizioni)(IT)[!][issue 1996-06][EARSAN CD VII].iso / earcd / arexx / rxdssppr.lha / rexxdossupport / doc / rexxdossupport.doc
Text File  |  1996-03-20  |  27KB  |  825 lines
  1. TABLE OF CONTENTS
  2.  
  3. rexxdossupport.library/--Disclaimer--
  4. rexxdossupport.library/--background--
  5. rexxdossupport.library/--history--
  6. rexxdossupport.library/--installation--
  7. rexxdossupport.library/AbsolutePath
  8. rexxdossupport.library/AddPart
  9. rexxdossupport.library/Delete
  10. rexxdossupport.library/DeleteVar
  11. rexxdossupport.library/Fault
  12. rexxdossupport.library/FilePart
  13. rexxdossupport.library/GetVar
  14. rexxdossupport.library/MakeDir
  15. rexxdossupport.library/MatchPattern
  16. rexxdossupport.library/ParsePattern
  17. rexxdossupport.library/PathPart
  18. rexxdossupport.library/ReadArgs
  19. rexxdossupport.library/Rename
  20. rexxdossupport.library/SetComment
  21. rexxdossupport.library/SetProtection
  22. rexxdossupport.library/SetVar
  23. rexxdossupport.library/--Disclaimer--   rexxdossupport.library/--Disclaimer--
  24.  
  25. Disclaimer
  26. ----------
  27.  
  28.    Permission is granted to make and distribute verbatim copies  of  this
  29. manual provided the copyright  notice  and  this  permission  notice  are
  30. preserved on all copies.
  31.  
  32. COPYRIGHT
  33.  
  34.    Copyright (C) 1994-1996 by hartmut Goebel
  35.  
  36.    No program, document, data file or  source  code  from  this  software
  37. package, neither in whole nor in part, may be included or used  in  other
  38. software packages unless it is authorized by a  written  permission  from
  39. the author.
  40.  
  41.  
  42. NO WARRANTY
  43.  
  44.    There is no warranty for this software package.  Although  the  author
  45. has tried to prevent errors, he can't guarantee that the software package
  46. described in this document is 100% reliable. You are therefore using this
  47. material at your own risk. The author cannot be made responsible for  any
  48. damage which is caused by using this software package.
  49.  
  50.  
  51. DISTRIBUTION
  52.  
  53.    This software package is freely distributable. It may be  put  on  any
  54. media which is used for the distribution of free  software,  like  Public
  55. Domain disk collections, CDROMs, FTP servers or bulletin board systems.
  56.  
  57.    In  order  to  ensure  the  integrity  of   this   software   package,
  58. distributors should use the original archive file  rexxdossuppor.lha.
  59. The author cannot be  made  responsible  if  this software  package   has
  60. become unusable due to modifications of  the  archive  contents   or   of
  61. the archive file itself.
  62.  
  63.    There is no limit on the costs  of  the  distribution,  e.g.  for  the
  64. media, like floppy disks, streamer tapes or compact disks, or the process
  65. of duplicating. Such limits have been proven to be harmful to the idea of
  66. freely distributable software, e.g. instead of reducing the price of  the
  67. floppy disk below the limit, the software was  simply  removed  from  the
  68. master disk.
  69.  
  70.    Although the author does not impose any limit on the  distribution  of
  71. this software package, he would like to express his personal opinions  on
  72. this matter:
  73.  
  74.    * This software package should be made available to everyone  free  of
  75.      charge whenever it is possible.
  76.  
  77.    * If you have acquired this software package under  normal  conditions
  78.      from a Public Domain dealer on a floppy disk at a price higher  than
  79.      5DM or US $5, then you have definitely paid too much.  Please  don't
  80.      support this improper profit making  any  longer  and  switch  to  a
  81.      cheaper source as soon as possible.
  82.  
  83.  
  84. USAGE RESTRICTIONS
  85.  
  86.    No program, document, data file or  source  code  from  this  software
  87. package, neither in whole nor in part, may be used on any  machine  which
  88. is used
  89.  
  90.    * for the research, development, construction, testing  or  production
  91.      of weapons or other military applications. This  also  includes  any
  92.      machine which is  used  in  the  education  for  any  of  the  above
  93.      mentioned purposes.
  94.  
  95.    * by people who accept, support or use violence against other  people,
  96.      e.g. citizens from foreign countries.
  97.  
  98. rexxdossupport.library/--background--   rexxdossupport.library/--background--
  99.  
  100.                 rexxdossupport.library 3.4
  101.                 ==========================
  102.  
  103.          Copyright (C) 1994-1996 by hartmut Goebel
  104.  
  105.  
  106.    After programming ARexx script for quite a while, I missed some
  107.    function found in dos.library --  especially access to
  108.    environment variables and the comfortable argument parsing. Since
  109.    there seamed to be no ARexx function library which implements
  110.    this functions, I decited to write my own. And here it is.
  111.  
  112.    This are the functions handled by this library.
  113.    · ReadArgs()
  114.    · GetVar(), SetVar(), DeleteVar()
  115.    · ParsePattern(), MatchPattern() - even case-insensitive
  116.    · Fault()
  117.    · Delete(), Rename(), MakeDir()
  118.    · SetComment(), SetProtection()
  119.    · FilePart(), PathPart(), AddPart()
  120.  
  121.    This additional functions have been added for your convinience:
  122.    · AbsolutePath()
  123.  
  124.    Enjoy it!
  125.    +++hartmut
  126.  
  127. rexxdossupport.library/--history--         rexxdossupport.library/--history--
  128.  
  129.  
  130.   3.4  20 Mar 1996
  131.        · fixed FilePart(): last charakter has been stripped
  132.          (ack: Nick Ring)
  133.   3.3  06 Mar 1996
  134.        · revised autodocs a bit
  135.   3.2  23 Feb 1996
  136.        · improofed docs about accessing local environment varibales
  137.        · fixed some erratas
  138.   3.1  16 Feb 1996
  139.        · new functions: AddPart(), FilePart(), PathPart()
  140.          (suggested many times)
  141.        · ReadArgs supports /T now (suggested by Magnus Holgren)
  142.   3.0  17 Jan 1996 [Kai Bolay]
  143.        · new function: AbsolutePath()
  144.  
  145.   2.4  11 Oct 1995
  146.        · fixed memory lose in ReadArgs (ack: Alexander Stirmlinger)
  147.        · ReadArgs example is now complete (ack: Oliver Creighton)
  148.   2.3  01 Apr 1995
  149.        · fixed problem with synonyms: foo=bar lead to illegal
  150.          variable named 'FOO=BAR'. Now allways th first synonym is
  151.          taken as var-name.
  152.   2.2  18 Jul 1994
  153.        · Shame on me! library names must be lowercase
  154.        · Some more notes in documentation
  155.   2.1  03 Jun 1994
  156.        · removed curious bug in ReadArgs() (uninitialized var,
  157.          introduced in V2.0)
  158.   2.0  07 May 1994 (never released)
  159.        · stronger check for present args to avoid NIL-Traps
  160.        · new functions: Delete(), Rename(), MakeDir(),
  161.                         SetComment(), SetProtection()
  162.   1.4  01 Feb 1994
  163.        · only significant part of parsed pattern is copied
  164.          into the ARexx Argstring
  165.   1.3  23 Jan 1994
  166.        · uses module RxLibsSupport [hG]
  167.   1.2  18 Jan 1994
  168.        · finished dokumentation
  169.        · UnsetVar() - like shell commnad - renamed to
  170.          DeleteVar() - like in dos.library
  171.        · SetVar() no longer accepts option "Binary"
  172.   1.1  16 Jan 1994
  173.        initial release
  174.  
  175. rexxdossupport.library/--installation--rexxdossupport.library/--installation--
  176.  
  177.    To use rexxdossupport.library, just copy is to yout LIBS:
  178.    directory. That's all.
  179.  
  180.    The LVO for the ARexx-Dispatcher is -30.
  181.        NB: it's the only LVO for this library :-)
  182.  
  183.    So, in every ARexx-Script you want to use rexxdossupport.library,
  184.    insert
  185.  
  186.       call addlib("rexxdossupport.library",0,-30,2)
  187.  
  188.    somewhere before the first call to one of the routines
  189.    implemented in this library.
  190.    Since ARexx does not check whether the lib can be opened but only
  191.    inserts the name into a list, the result value from addlib() can
  192.    be ignored in most cases. The value would be interesting to check
  193.    if the added note will require the same library version, but I
  194.    don't know how to find this out.
  195.  
  196. rexxdossupport.library/AbsolutePath       rexxdossupport.library/AbsolutePath
  197.  
  198.    NAME
  199.        AbsolutePath -- Returns the fully qualified path of a file or dir (V3)
  200.  
  201.    SYNOPSIS
  202.        path = AbsolutePath( name )
  203.  
  204.    FUNCTION
  205.        Determines the absolute path of a file or directory.
  206.  
  207.    INPUTS
  208.        name  - file or directory name
  209.  
  210.    RESULT
  211.        path  - absolute path to file/dir
  212.  
  213.        RC (rexx variable) - 5 when file does not exist,
  214.                             0 otherwise
  215.  
  216.    EXAMPLE
  217.        /* */
  218.        path = AbsolutePath(":s/Startup-Sequence")
  219.        if RC = 5 then
  220.          say "File ':s/Startup-Sequence' does not exist"
  221.        else
  222.          say "':s/Startup-Sequence' is '" || path || "'"
  223.  
  224.    SEE ALSO
  225.      dos.library/NameFromLock()
  226.  
  227. rexxdossupport.library/AddPart                 rexxdossupport.library/AddPart
  228.  
  229.    NAME
  230.        AddPart -- Appends a file/dir to the end of a path (V3)
  231.  
  232.    SYNOPSIS
  233.        newpath = AddPart( dirname , filename )
  234.  
  235.    FUNCTION
  236.        This funktion adds a file, directory, or subpath name to a
  237.        directory path name taking into account any required
  238.        seperator charakters.
  239.  
  240.    INPUTS
  241.        dirname  - the path to add a fir/directory name to.
  242.        filename - the filename or directory name to add.
  243.  
  244.    RESULT
  245.        newpath  - resulting path.
  246.  
  247.        RC (rexx variable) - 5 when file does not exist,
  248.                             0 otherwise
  249.  
  250.    EXAMPLE
  251.        /* */
  252.        path = AddPart("System:s/","Startup-Sequence")
  253.        if RC = 0 then say path
  254.          /* --> System:s/Startup-Sequence */
  255.  
  256.        path = AddPart("System:s/bla",":Startup-Sequence")
  257.        if RC = 0 then say path
  258.          /* --> System:Startup-Sequence */
  259.  
  260.        path = AddPart("System:s/bla","/Startup-Sequence")
  261.        if RC = 0 then say path
  262.          /* --> System:s/bla//Startup-Sequence */
  263.  
  264.    BUGS
  265.        Neither the input dirname nor the resulting path must exceed
  266.        511 Bytes. If a string overflow occurrs, error 'string too
  267.        long' will be returned which ARexx outputs as 'string > 65535
  268.        charakters'.
  269.  
  270.    SEE ALSO
  271.        dos.library/AddPart(), FilePart(), PathPart()
  272.  
  273. rexxdossupport.library/Delete                   rexxdossupport.library/Delete
  274.  
  275.    NAME
  276.        Delete -- Delete a file or directory (V2)
  277.  
  278.    SYNOPSIS
  279.        success = Delete( name )
  280.  
  281.    FUNCTION
  282.        This attempts to delete the file or directory specified by
  283.        'name'. If the deletion fails an error is returned and the
  284.        rexx variable RC is set. Note that all the files within a
  285.        directory must be deleted before the directory itself can be
  286.        deleted.
  287.  
  288.    INPUTS
  289.        name     - name of file or directory to delete.
  290.  
  291.    RESULT
  292.        success - If TRUE, the file was sucessfully deleted,
  293.                  FALSE indicates failure.
  294.  
  295.        RC (rexx variable) - contains the dos error code if the
  296.                function was not successfull. This can can directly
  297.                be used as input for Fault().
  298.  
  299.    SEE ALSO
  300.        Fault(), dos.library/DeleteFile()
  301.  
  302. rexxdossupport.library/DeleteVar             rexxdossupport.library/DeleteVar
  303.  
  304.    NAME
  305.        DeleteVar -- Deletes a local or environment variable
  306.  
  307.    SYNOPSIS
  308.        success = DeleteVar( name, [ "Local" | "Global" ] )
  309.  
  310.    FUNCTION
  311.        Deletes a local or environment variable.
  312.  
  313.    INPUTS
  314.        name     - variable name.  Note variable names follow
  315.                   filesystem syntax and semantics.
  316.        "Global" - tries to get a global env variable.
  317.        "Local"  - tries to get a local variable (see note below).
  318.  
  319.                 The default is to delete a local variable if found, otherwise
  320.                 a global environment variable if found.
  321.  
  322.    RESULT
  323.        success - If TRUE, the variable was sucessfully deleted,
  324.                  FALSE indicates failure.
  325.  
  326.    NOTES
  327.       Since ARexx spawn a new process of each script -- even if
  328.       started from Shell -- option "Local" may not work as supposed.
  329.  
  330.    SEE ALSO
  331.        GetVar(), SetVar(), dos.library/DeleteVar()
  332.  
  333. rexxdossupport.library/Fault                     rexxdossupport.library/Fault
  334.  
  335.    NAME
  336.        Fault -- Returns the text associated with a DOS error code
  337.  
  338.    SYNOPSIS
  339.        string = Fault( code, header )
  340.  
  341.    FUNCTION
  342.        This routine obtains the error message text for the given
  343.        error code. The header is prepended to the text of the error
  344.        message, followed by a colon. By convention, error messages
  345.        should be no longer than 80 characters, and preferably no
  346.        more than 60.
  347.  
  348.        The value returned by IoErr() (not available in this library)
  349.        is set to the code passed in. If there is no message for the
  350.        error code, the message will be "Error code <number>\n".
  351.  
  352.        The string will be empty if the code passed in was 0.
  353.  
  354.    INPUTS
  355.        code   - Error code
  356.        header - header to output before error text
  357.  
  358.    RESULT
  359.        string - error massage as described above.
  360.  
  361.        RC (rexx variable) - 5 when error message is empty
  362.                             0 otherwise
  363.  
  364.    BUGS
  365.       I've been told that this function returns only an empty sting.
  366.       Since nobody gave me further information, I can't fix it.
  367.  
  368.    SEE ALSO
  369.        dos.library/Fault(), dos.library/IoErr()
  370.  
  371. rexxdossupport.library/FilePart               rexxdossupport.library/FilePart
  372.  
  373.    NAME
  374.        FilePart -- Returns the last component of a path (V3)
  375.  
  376.    SYNOPSIS
  377.        part = FilePart( path )
  378.  
  379.    FUNCTION
  380.        This function returns the last component of a string path
  381.        specification, which will normally be the file name.  If there is
  382.        only one component, it returns the complete string.
  383.  
  384.    INPUTS
  385.        path - pointer to an path string.  May be relative to the current
  386.               directory or the current disk.
  387.  
  388.    RESULT
  389.        part  - resulting path part.
  390.  
  391.    EXAMPLE
  392.        /* */
  393.        say FilePart("xxx:yyy/zzz/qqq")
  394.          /* --> qqq */
  395.        say FilePart("xxx:yyy")
  396.          /* --> yyy */
  397.  
  398.    SEE ALSO
  399.        dos.library/FilePart(), AddPart(), PathPart()
  400.  
  401. rexxdossupport.library/GetVar                   rexxdossupport.library/GetVar
  402.  
  403.    NAME
  404.        GetVar -- Returns the value of a local or global variable
  405.  
  406.    SYNOPSIS
  407.        string = GetVar( name, ["Local" | "Global"], ["Binary"] )
  408.  
  409.    FUNCTION
  410.        Gets the value of a local or environment variable.  It is advised to
  411.        only use ASCII strings inside variables, but not required.  This stops
  412.        putting characters into the destination when a \n is hit, unless
  413.        "Binary" is specified.  (The \n is not stored in the buffer.)
  414.  
  415.    INPUTS
  416.        name     - variable name.
  417.        "Global" - tries to get a global env variable.
  418.        "Local"  - tries to get a local variable (see note below).
  419.        "Binary" - don't stop at \n
  420.                   in this mode the string returned is not null terminated
  421.  
  422.                 The default is to try to get a local variable first,
  423.                 then to try to get a global environment variable.
  424.  
  425.    RESULT
  426.        string - contents of the variable
  427.  
  428.        RC (rexx variable) - 5 when variable does not exist,
  429.                             0 otherwise
  430.  
  431.    EXAMPLE
  432.        /* */
  433.        username = GetVar("username")
  434.        if RC = 5 then
  435.          say "Variable 'username' is not set"
  436.        else
  437.          say "Variable 'username' is" username
  438.  
  439.    NOTES
  440.       Contents may be max. 512 char.
  441.  
  442.       Since ARexx spawns a new process of each script -- even if
  443.       started from Shell -- option "Local" may not work as supposed.
  444.       But one can
  445.  
  446.                        |  Callie may  |  Callie may
  447.         Calling order  |     read     |     write
  448.                        | callers vars | to callers vars
  449.        ----------------+--------------+-------------------
  450.         Shell -> Arexx |      no      |      no
  451.         ARexx -> Shell |     yes      |      no
  452.         ARexx -> Arexx |      no      |      no
  453.  
  454.    BUGS
  455.        Due to a bug in dos.library, binary global vars will be null
  456.        terminated in V37, V38.
  457.  
  458.    SEE ALSO
  459.      SetVar(), DeleteVar(), dos.library/GetVar()
  460.  
  461. rexxdossupport.library/MakeDir                 rexxdossupport.library/MakeDir
  462.  
  463.    NAME
  464.        MakeDir -- Create a new directory (V2)
  465.  
  466.    SYNOPSIS
  467.        success = MakeDir( name )
  468.  
  469.    FUNCTION
  470.        MakeDir creates a new directory with the specified name. If
  471.        it fails an error is returned and the rexx variable RC is
  472.        set.  Directories can only be created on devices which
  473.        support them, e.g. disks.
  474.  
  475.    INPUTS
  476.        name     - name of directory to create
  477.  
  478.    RESULT
  479.        success - If TRUE, the variable was sucessfully deleted,
  480.                  FALSE indicates failure.
  481.  
  482.        RC (rexx variable) - contains the dos error code if the
  483.                function was not successfull. This can can directly
  484.                be used as input for Fault().
  485.  
  486.    SEE ALSO
  487.        Fault(), dos.library/CreateDir()
  488.  
  489. rexxdossupport.library/MatchPattern       rexxdossupport.library/MatchPattern
  490.  
  491.    NAME
  492.        MatchPattern --  Checks for a pattern match with a string
  493.  
  494.    SYNOPSIS
  495.        match = MatchPattern(pattern, string, ["Nocase"], ["Parsed"] )
  496.  
  497.    FUNCTION
  498.        Checks for a pattern match with a string.
  499.        This routine is case-sensitive by default. Use option
  500.        "NoCase" for case-insensitve matching.
  501.  
  502.        Use option "Parsed" to indicate that pattern has already been
  503.        tokenized using ParsePattern(). Make sure to use or use not
  504.        "NoCase" for both function.
  505.  
  506.    INPUTS
  507.        pattern  - pattern string to match
  508.        string   - string to match against given pattern
  509.        "Nocase" - match should be case-insensitve
  510.        "Parsed" - pattern has already been parsed using ParsePattern()
  511.  
  512.    RESULT
  513.        match - success or failure of pattern match.
  514.  
  515.    SEE ALSO
  516.        ParsePattern(), dos.library/MatchPattern(),
  517.        dos.library/MatchPatternNoCase()
  518.  
  519. rexxdossupport.library/ParsePattern       rexxdossupport.library/ParsePattern
  520.  
  521.    NAME
  522.        ParsePattern -- Create a tokenized string for MatchPattern()
  523.  
  524.    SYNOPSIS
  525.        token = ParsePattern( pattern, ["NoCase"] )
  526.  
  527.    FUNCTION
  528.        Tokenizes a pattern, for use by MatchPattern().  Also indicates
  529.        if there are any wildcards in the pattern (i.e. whether it might match
  530.        more than one item).
  531.  
  532.        For a description of the wildcards, see dos.library/ParsePattern().
  533.  
  534.    INPUTS
  535.        pattern  - unparsed wildcard string to search for.
  536.  
  537.    RESULT
  538.        token    - output string, tokenized version of input.
  539.  
  540.        RC (rexx variable) - 5 when does not contain wildcards
  541.                             0 otherwise
  542.  
  543.    BUGS
  544.        Since is't not clear wether the resulting token may contain
  545.        null charakters, the returned string is always
  546.        2 * Length(pattern) + 2 bytes long.
  547.  
  548.    SEE ALSO
  549.        ParsePattern(), dos.library/ParsePattern(),
  550.        dos.library/ParsePatternNoCase()
  551.  
  552. rexxdossupport.library/PathPart               rexxdossupport.library/PathPart
  553.  
  554.    NAME
  555.        PathPart -- Strips the next-to-last component of a path. (V3)
  556.  
  557.    SYNOPSIS
  558.        part = PathPart( path )
  559.  
  560.    FUNCTION
  561.        This function strips the next-to-last component of a path
  562.        specification, which will normally result in the directory name.
  563.        If there is only one component, it returns an empty string.
  564.  
  565.    INPUTS
  566.        path - path string.  May be relative to the current directory or
  567.              the current disk.
  568.  
  569.    RESULT
  570.        part  - resulting path part.
  571.  
  572.    EXAMPLE
  573.        /* */
  574.        say FilePart("xxx:yyy/zzz/qqq")
  575.          /* --> xxx:yyy/zzz */
  576.        say FilePart("xxx:yyy")
  577.          /* --> xxx: */
  578.  
  579.    SEE ALSO
  580.        dos.library/PathPart(), AddPart(), FilePart()
  581.  
  582. rexxdossupport.library/ReadArgs               rexxdossupport.library/ReadArgs
  583.  
  584.    NAME
  585.        ReadArgs -- Parse argument string using Dos/ReadArgs()
  586.  
  587.    SYNOPSIS
  588.        okay = ReadArgs( arguments, template, [stem] )
  589.  
  590.    FUNCTION
  591.        Parses an argument string according to a template. See
  592.        dos.library/ReadArgs() for details and describtion of the
  593.        template.
  594.  
  595.        This function supports the following template options:
  596.  
  597.        /S - Switch.  Resulting variable will be either true (1) or
  598.             false (0).
  599.        /T - Toggle.  (V3) Results like /S, but much more mighty,
  600.                      see below.
  601.        /N - Number.
  602.        /M - Multiple strings.  See below for further information.
  603.  
  604.        /K - Keyword.      }
  605.        /A - Required.     }  handled by dos
  606.        /F - Rest of line. }
  607.  
  608.    INPUTS
  609.        arguments - the string to be parsed
  610.        template  - dos.library/ReadArgs()-style like template
  611.        stem      - stem prefix for resulting variables (optional)
  612.  
  613.        For /T arguments the corresponding variable (see RESULTS) is read
  614.        to get the default.  The variable must be either false (0) or true
  615.        (1).  If the variable does not exist, the default is false (0).
  616.  
  617.    RESULT
  618.        okay  - boolean value indicating success.
  619.  
  620.        RC (rexx variable) - contains the dos error code if the
  621.                function was not successfull. This can can directly
  622.                be used as input for Fault().
  623.  
  624.        For each item in the template which has a corresponding
  625.        argument, a Rexx variable will be created. The variable's
  626.        name is the item's name prefixed by the stem name (if given). If
  627.        an item name has synonyms, the first one will be taken as variable
  628.        name.
  629.  
  630.        Items with option /M will result in a stem variable with a
  631.        .COUNT node containing the number of elements. If no fitting
  632.        arguments is passed, .COUNT will be zero.
  633.        The entries will be in stem nodes .0 to .n (where n is
  634.        .COUNT-1).
  635.  
  636.    EXAMPLE
  637.        /* ReadArgsExample.rexx */
  638.        If ~show('L', 'rexxdossupport.library') then do
  639.          if ~addlib('rexxdossupport.library', 0, -30, 2) then do
  640.           say "rexxdossupport.library not available, exiting ..."
  641.           exit 20
  642.          end
  643.        end
  644.  
  645.        parse arg args /* get the arguments w/o ARexx-Parsing */
  646.  
  647.        template = "Files/M,Method/K,MinSize/K/N,Test/S,Toggle/T"
  648.  
  649.        /* set defaults */
  650.        Method = "NUKE"; MinSize = 512;
  651.  
  652.        /* no stem given: results are assigned to simple variables */
  653.  
  654.        if ReadArgs(args,template) then
  655.          say 'Method='method ' MinSize='MinSize 'Test=' test 'Toggle='toggle
  656.          do i = 0 by 1 for files.count
  657.            say files.i
  658.          end
  659.  
  660.        /* stem given: results are assigned to stem variable */
  661.        /* since the default values are set as non-stem variables,
  662.         * they are not overwritten by the following call even if
  663.         * given
  664.         */
  665.  
  666.        drop method MinSize test /*toggle is kept! */
  667.  
  668.        if ReadArgs(args,template,"args.") then
  669.          say 'Method ='args.method 'MinSize='args.MinSize
  670.          say 'Test=' args.test 'Toggle='args.toggle
  671.          do i = 0 by 1 for args.files.count
  672.            say args.files.i
  673.          end
  674.  
  675.    NOTE
  676.       /T was unsupported till V 3.1
  677.  
  678.    NOTE
  679.       Some background about /T which is not documented well:
  680.       /T acts very like /S but may be set to on/off using the keywords
  681.       'YES'/'ON' and 'NO'/'OFF'. This is usefull when parsing eg.
  682.       tool-types or using multible option-sources (eg. defaults taken
  683.       from an environment variable).
  684.  
  685.                                   /S             /T
  686.         1st option-set          UseScreen     UseScreen=YES
  687.         2nd option-set        NoUseScreen     UseScreen=NO
  688.           --> results into   ??confusion??    UseScreen=NO
  689.  
  690.    SEE ALSO
  691.       Fault(), dos.library/ReadArgs()
  692.  
  693. rexxdossupport.library/Rename                   rexxdossupport.library/Rename
  694.  
  695.    NAME
  696.        Rename -- Rename a directory or file (V2)
  697.  
  698.    SYNOPSIS
  699.        success = Rename( oldName, newName )
  700.  
  701.    FUNCTION
  702.        Rename() attempts to rename the file or directory specified
  703.        as 'oldName' with the name 'newName'. If the file or
  704.        directory 'newName' exists, Rename() fails and returns an
  705.        error. Both 'oldName' and the 'newName' can contain a
  706.        directory specification. In this case, the file will be moved
  707.        from one directory to another.
  708.  
  709.        Note: it is impossible to Rename() a file from one volume to
  710.        another.
  711.  
  712.    INPUTS
  713.        oldName - pointer to a null-terminated string
  714.        newName - pointer to a null-terminated string
  715.  
  716.    RESULT
  717.        success - If TRUE, the variable was sucessfully deleted,
  718.                  FALSE indicates failure.
  719.  
  720.        RC (rexx variable) - contains the dos error code if the
  721.                function was not successfull. This can can directly
  722.                be used as input for Fault().
  723.  
  724.    SEE ALSO
  725.        Fault(), dos.library/Rename()
  726.  
  727. rexxdossupport.library/SetComment           rexxdossupport.library/SetComment
  728.  
  729.    NAME
  730.        SetComment -- Change a files' comment string (V2)
  731.  
  732.    SYNOPSIS
  733.        success = SetComment( name, comment )
  734.  
  735.    FUNCTION
  736.        SetComment() sets a comment on a file or directory. The
  737.        comment may be up to 80 characters in the current ROM
  738.        filesystem (and RAM:).  Note that not all filesystems will
  739.        support comments (for example, NFS usually will not), or the
  740.        size of comment supported may vary.
  741.  
  742.    INPUTS
  743.        name     - name of file or directory to set comment
  744.        comment  - comment to be set
  745.  
  746.    RESULT
  747.        success - If TRUE, the variable was sucessfully deleted,
  748.                  FALSE indicates failure.
  749.  
  750.        RC (rexx variable) - contains the dos error code if the
  751.                function was not successfull. This can can directly
  752.                be used as input for Fault().
  753.  
  754.    SEE ALSO
  755.        SetProtection(), Fault(), dos.library/SetComment()
  756.  
  757. rexxdossupport.library/SetProtection     rexxdossupport.library/SetProtection
  758.  
  759.    NAME
  760.        SetProtection -- Set protection for a file or directory (V2)
  761.  
  762.    SYNOPSIS
  763.        success = SetProtection( name, mask )
  764.  
  765.    FUNCTION
  766.        SetProtection() sets the protection attributes on a file or
  767.        directory.  See <dos/dos.h> for a listing of protection bits.
  768.  
  769.        The archive bit should be cleared by the filesystem whenever
  770.        the file is changed.  Backup utilities will generally set the
  771.        bit after backing up each file.
  772.  
  773.        The V36 Shell looks at the execute bit, and will refuse to
  774.        execute a file if it is set.
  775.  
  776.        Other bits will be defined in the <dos/dos.h>include files.
  777.        Rather than referring to bits by number you should use the
  778.        definitions in <dos/dos.h>.
  779.  
  780.    INPUTS
  781.        name     - name of file or directory to set protection
  782.        mask     - the protection mask required
  783.  
  784.    RESULT
  785.        success - If TRUE, the variable was sucessfully deleted,
  786.                  FALSE indicates failure.
  787.  
  788.        RC (rexx variable) - contains the dos error code if the
  789.                function was not successfull. This can can directly
  790.                be used as input for Fault().
  791.  
  792.    SEE ALSO
  793.        SetComment(), Fault(), dos.library/SetProtection()
  794.  
  795. rexxdossupport.library/SetVar                   rexxdossupport.library/SetVar
  796.  
  797.    NAME
  798.        SetVar -- Sets a local or environment variable
  799.  
  800.    SYNOPSIS@{ub}
  801.        success = SetVar( name, ["Local" | "Global"] )
  802.  
  803.    FUNCTION
  804.        Sets a local or environment variable.  It is advised to only use
  805.        ASCII strings inside variables, but not required.
  806.  
  807.    INPUTS
  808.        name     - variable name.
  809.        "Global" - tries to get a global env variable.
  810.        "Local"  - tries to get a local variable (see note below).
  811.  
  812.                The default is to set a local environment variable.
  813.  
  814.    RESULT
  815.        success - If non-zero, the variable was sucessfully set, FALSE
  816.                  indicates failure.
  817.  
  818.    NOTES
  819.       Since ARexx spawn a new process of each script -- even if
  820.       started from Shell -- option "Local" may not work as supposed.
  821.  
  822.    SEE ALSO
  823.      GetVar(), DeleteVar(), dos.library/SetVar()
  824.  
  825.